updateOrder

HTTP method: POST

Use the updateOrder to update the order amount, add, remove or update order lines and update order details.


The following diagram describes a typical updateOrder flow using the Merchant API.

Select one of the payment methods that supports update order to see the parameters relevant for that method:

Parameter Description Type Mandatory
payment_id

The id of a specific payment.

 [0-9a-f]{1,32} Yes
amount

This is the gross amount to be updated to (including taxes). In cases of invoice payments it should match the gross total amount of order lines.

You must use a dot as the decimal separator, and the amount can have maximum 2 decimals.

 float Yes - It can be optional when transaction_info is provided
orderLines Listing of order lines. (Only relevant for invoice payment methods such as KlarnaPayments) Array
See table below
No
In case it's not passed, it will remove all the order lines
transaction_info

This is a one-dimensional associative array, where you can put any value that you would like to associate with the payment in the call to createPaymentRequest.

Array

Maximum 50 entries of maximum 255 characters each.

No
customer_info Listing of customer info for updating shipping details. (Only relevant for KlarnaPayments) Array
See table below
No
In case it's not passed, it will not do anything
trackingInfo[]

Tracking information, in an array. Could include:

trackingId Id of the tracking. Maximum 100 characters.
refTrackingId Id of the referred tracking. Maximum 100 characters. Used to identify the related tracking. For Klarna Payments this can be used to link the return tracking to the shipping tracking.
companyName Name of the shipping company. Maximum 100 characters. You are advised to be as specific as possible, including the region/branch, etc where appropriate
method Allowed values matches (PickUpStore|Home|BoxReg|BoxUnreg|PickUpPoint|Own)
trackingNumber Tracking number for the shipment. Maximum 100 characters
trackingUri URL where the customer can track their shipment. Maximum 1024 characters
type Type of the tracking information. Possible values: SHIPPING, RETURN
trackingInfo[0][trackingId] = 1
trackingInfo[0][companyName] = Mærsk
trackingInfo[0][method] = PickUpStore
trackingInfo[0][trackingNumber] = 123abc
trackingInfo[0][trackingUri] = www.tracking.com/id
trackingInfo[0][type] = SHIPPING
trackingInfo[1][trackingId] = 2
trackingInfo[1][refTrackingId] = 1
trackingInfo[1][companyName] = ReturnCo
trackingInfo[1][trackingNumber] = 456abc
trackingInfo[1][trackingUri] = www.tracking.com/id2
trackingInfo[1][type] = RETURN

See https://docs.klarna.com/api/ordermanagement/#operation/captureOrder

Please make sure you passed same number of tracking info of SHIPPING type with the RETURN type so that it can be mapped correctly with the KlarnaPayments shipping_info

Array
No
In case it's not passed, it will not do anything

Order lines

Parameter Description Type Mandatory
orderLines The individual line items of the order. Array
Yes

For each order line:

Value

Description

Type

Mandatory

description

Description of an item.

String (255)

Yes

itemId

The item identification.

Each itemId must be unique within an order.

String (100)

Yes

quantity

The quantity of the item. The value must be greater than zero.

Decimal

Yes

unitPrice

The unit price, excluding sales tax. The value must be greater than zero, unless the optional goodsType parameter is set to handling, in which case the field can be used to provide a discount.

Decimal

Yes

taxPercent

This is the tax percentage of the unit price.

Send both the taxPercent and taxAmount parameters in the method call. If you provide only one, the other is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.

Decimal

No

taxAmount

This is the total tax on an order line, before any discounts are applied. It is recommended to use taxAmount if possible. If you provide both taxPercent and taxAmount, the amount takes precedence.

Send both the taxPercent and taxAmount parameters in the method call. If you provide only one of the taxPercent and taxAmount parameters, the other parameter is inferred, and rounding errors may occur.
The taxAmount is used for the calculation, and taxPercent is printed on the invoice.

Decimal

Yes

unitCode

The relevant measurement unit for the order line. For example, kg.

String (50)

 

discount

The order line's discount in percent.

Decimal

 
goodsType

The goods type of the order line - shipment | handling | item | digital | discount | gift_card| physical | sales_tax

  

imageUrl

The full URL of the icon for the item

String (255)

 
productUrl The full URL for the description of the item String (255)  

Customer Info (Only KlarnaPayments)

If you wish to update shipping information in addition to general payment information, then please provide the following format for customer_info parameters as seen in Create Payment Request's Customer information parameters section.

The relevant fields for the updateOrder call with KlarnaPayments are: shipping_lastname, shipping_firstname, shipping_address, shipping_postal, shipping_region, shipping_country, shipping_city, email, customer_phone and company_name

In case of failure during the updateOrder call you may receive a PartialSuccess response, meaning that general payment information was updated but shipping information failed to update. The reason will be provided in <MerchantErrorMessage> in the response.

The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).

Parameter Description Type
Result Success, PartialSuccess or Error. string
Test URL https://testgateway.altapaysecure.com/merchant/API/<method>
Production URL https://<YourShopName>.altapaysecure.com/merchant/API/<method>

Request

  curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/updateOrder \
  --header 'Authorization: Basic auth' \
  --data payment_id=55 \
  --data amount=144.70 \
  --data `orderLines[0][description]`=Product1 \
  --data `orderLines[0][itemId]`=abc123 \
  --data `orderLines[0][quantity]`=2 \
  --data `orderLines[0][taxAmount]`=10.00 \
  --data `orderLines[0][unitCode]`=pcs \
  --data `orderLines[0][unitPrice]`=20.00 \
  --data `orderLines[0][discount]`=5 \
  --data `orderLines[1][description]`=Product2 \
  --data `orderLines[1][itemId]`=def456 \
  --data `orderLines[1][quantity]`=3 \
  --data `orderLines[1][taxPercent]`=8 \
  --data `orderLines[1][unitCode]`=pcs \
  --data `orderLines[1][unitPrice]`=30.00 \
  --data `orderLines[1][discount]`=0 \

XML result

<?xml version="1.0" encoding="utf-8" ?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-09-29T12:34:56+02:00</Date>
		<Path>API/updateOrder</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<Result>Success</Result>
	</Body>
</APIResponse>

Partial Success Result Example

<?xml version="1.0"?>
<APIResponse version="20170228">
    <Header>
        <Date>2023-06-28T08:49:16+00:00</Date>
        <Path>API/updateOrder</Path>
        <ErrorCode>0</ErrorCode>
        <ErrorMessage/>
    </Header>
    <Body>
        <Result>PartialSuccess</Result>
        <MerchantErrorMessage>Partial Error in [Update Customer Details]: UNPROCESSABLE_ENTITY ['shipping_address.postal_code' size must be between 0 and 10 (was 19)]</MerchantErrorMessage>
        <MerchantErrorCode>240000</MerchantErrorCode>
        <CardHolderMessageMustBeShown>false</CardHolderMessageMustBeShown>
    </Body>
</APIResponse>

You can update the order multiple times. To do this you should call the updateOrder method with the same payment_id as many times as you want.

If your request comes with partial success response, you can create a new request fixing the parameters in question and send the new request.

The provided order lines in the request will replace the existing order lines of an order.

The amount value should be equal to the total amount of the order lines.

The amount value cannot be smaller or equal to the captured amount.

The following formula describe how the total amount is calculated

Order line net-amount = quantity * unitPrice
Order line tax-amount = taxAmount if the parameter is sent in the request OR taxPercent * net-amount / 100
Order line gross-amount = net-amount + tax-amount
Order line discount-amount = discount * gross-amount / 100
Order line gross-amount-with-discount = gross-amount - discount-amount
Total amount = sum of gross-amount-with-discount of all the order lines